UIS Command Components

Devices > Remote Devices > UIS Commands > UIS Command Components

UIS Command Components

A UIS command contains the following components: a Component type, a Data group, an ordinal (Ord), and Parameters. A UIS command can have multiple instances of these components. Together, they define an action a given command takes on its associated data group(s).

Sample Command Component Fields

Sample Edit Command Component Dialog Box

Component Type

A component type defines the kind of action that a command does to one or more associated data groups. Component types vary by remote device (and protocol); each remote device has a predefined set of component types from which to choose. These are found on the Edit Command Component dialog box within the Component type drop-down menu.

Common component types include Get data group from device [DG_F_DEV] and Send data group to device [DG_T_DEV]. Not all component types apply to all data groups. Some have very specific applications, like the Clear All History Tx Info [CLRHSTXA] component for BSAP, Eagle, Emerson ROC, Emerson ROCPlus, FlowAuto, and Weatherford K-Series remote devices, and the Clear All Upload Log Tx Info [CLRLGTXA] component for the Amocams 700 remote device.

When a selected component type cannot be assigned to an individual data group, the Data group information fields of the Add/Edit Command Component dialog box remain dimmed.

Special UIS Command Component Types

There are several special command component types available.

Command Component Type

Description

Used by EIE

CLRCACHE

Clear Device Cache clears the internal caches for signal metadata, array dimensions, archive field map, missing signal map, and the list column cache. CLRCACHE has no command parameters.

BSAP

CLRHSTXA

Clear All History Tx Info clears all historical data group caches. CLRHSTXA has no command parameters.

Note: If you clear all caches using a UIS command, the cache values in each transaction of historical data groups are not reset; past transactions continue to display actual values. This is done for performance reasons so that each DDS transaction does not have to be updated. The driver ignores these cached values after the command has been issued.

Weatherford WellPilot DLQ/K-Series

CLRLGTXA

Clear All Upload Log Tx Info clears the cache for all data groups. CLRLGTXA has no command parameters. Also see Log Retrieval Optimization.

Amocams 700

CONFIG

Get RTU Configuration retrieves configuration information from the field device. CONFIG has no parameters.

Emerson Roc

Emerson RocPlus

Lufkin MPC

Weatherford WellPilot DLQ/K-Series

CYUPDTPT

Update CygNet Point updates the record for a CygNet point. CYUPDTPT has the following command parameters:

Parameter	Required	Description
FOnErr	No	Fail cmd on update error indicates to abort the UIS command if any update errors are encountered. The errors that might come up include: if the point specified in the Fac, Serv, Site, or UDC parameters does not exist, or if the point exists in a different UIS and any messaging errors or communication failure to that service comes up.
Fac	Yes	Facility for pt identifies the facility of the point to update.
Serv	No	Service for pt identifies the SERVICE of the point to update.
Site	No	Site for pt identifies the SITE of the point to update.
UDC	Yes	UDC for pt identifies the UDC of the point to update.
UType	No	Update type indicates the type of update. Value options are 0 - 3, where 0=Completion, 1=Success, 2=Failure, 3=Creation.
UsrMsk	No	User bit mask specifies the user bit mask of the point to update.
UsrVal	No	User bit value to match specifies the user bit value to match when updating the point record.
Value	No	Value indicates the point value to update.

All EIEs

CYWAITPT

Wait for CygNet Point signals the UIS to wait to perform a command until the value of the specified CygNet point changes to a specified value.

CYWAITPT must be the first command component added to a UIS command. You cannot add other instances of CYWAITPT to a UIS command.

CYWAITPT has the following command parameters:

Parameter	Required	Description
Dur	Yes	Duration is the amount of time (in HH:MM:SS or HH:MM or HH) for the UIS command to wait for the point value to change before timing out.
FOnErr	No	Fail on point error indicates to abort the UIS command if any error conditions are encountered. The point errors that might come up include: if the point specified in the Fac, Serv, Site, or UDC parameters does not exist, or if the point exists in a different UIS and any messaging errors or communication failure to that service comes up.
Fac	Yes	Facility for pt identifies the facility of the point on which to wait for the point value to change before performing the UIS command.
Int	Yes	Interval indicates the frequency (in HH:MM:SS or HH:MM or HH) with which the UIS will check the point’s value to see if it has changed.
Serv	No	Service for pt identifies the SERVICE of the point on which to wait for the point value to change before performing the UIS command.
Site	No	Site for pt identifies the SITE of the point on which to wait for the point value to change before performing the UIS command.
UDC	Yes	UDC for pt identifies the UDC of the point on which to wait for the point value to change before performing the UIS command.
UsrMsk	No	User bit mask specifies the user bit mask on which to wait for the status bit change before issuing the UIS command. Note: The user status bit parameters (UsrMsk and UsrVal) only apply to the extended status field of the point record, so they will not match anything in the base status.
UsrVal	No	User bit value to match specifies the user bit value to match before issuing the UIS command.
Value	No	Value to match specifies the value on which to wait for the point to change to before issuing the UIS command. Note: You can set parameters for both the point user status AND point value. So you can match either one by itself, or you can specify that both must match your parameter values.

All EIEs

GETPTALL

Get All Point Values retrieves all point values from the field device. GETPTALL has no command parameters.

Benchmark

GETPTEXC

Get All Exception Point Values retrieves all exception point values from the field device. GETPTEXC has no command parameters.

Benchmark

GETTIME

Get RTU Time retrieves time from the field device. GETTIME has no command parameters.

Emerson Roc

Emerson RocPlus

Weatherford WellPilot DLQ/K-Series

NRTBCAST

NRT/TimeSync Broadcast sends a broadcast NRT to all the devices in the hierarchy. NRTBCAST has no command parameters.

BSAP

NRTSEND

NRT/TimeSync Targeted sends a targeted NRT to all the devices in the hierarchy. NRTSEND has no command parameters.

BSAP

SETFRAME

Set Frame and DB Sequence Number overrides the version and framing number for protocol specific data.

SETFRAME has the following command parameters:

Parameter	Required	Description
DbSeqNum	No	Database sequence number
DbVerNum	No	Database version number
FrameNum	No	Frame number

BSAP

SETTIME

Set RTU Time sets time for the field device. SETTIME has no command parameters.

Emerson Roc

Emerson RocPlus

Weatherford WellPilot DLQ/K-Series

SIGNOFF

Sign Off. SIGNOFF has no command parameters.

Mercury

SIGNON

Sign On. SIGNON has no command parameters.

Mercury

STATUS

Get Current Status retrieves current status from the field device. STATUS has no command parameters.

Emerson Roc

Emerson RocPlus

Lufkin MPC

Weatherford WellPilot DLQ/K-Series

TXHISTRG

Transactional History Trigger defines a transaction set numeric ID, each of which corresponds to an Emerson transaction set numeric ID. Up to 10 transaction sets can be available, containing up to 100 transaction points each.

One TxSet parameter is required for each transaction set trigger you want to initiate from CygNet. You can use a UIS Command Button in CygNet Studio or some other mechanism for manually triggering a transaction, but you cannot trigger a transaction from a transactional data group editor dialog box in the Device Definition Service (DDS).

If you want to maintain a record of transaction set triggers initiated from CygNet, you must instantiate a "Transactional History Trigger" data group for each applicable transaction set. Records of CygNet-initiated triggers cannot be viewed as DDS transactions without this data group, although fields in the "Transactional History Cfg" data group editor(s) reflect the number of transactions.

Value options are 1 - 10 where each value represents a single transaction set. Multiple TXHISTRG command components can be added to a single UIS command.

This UIS command component and its parameters are only exposed in the Emerson ROCPlus EIE template file in the specCmds element.

Emerson RocPlus XML Example

</uccParms>

</TXHISTRG>

</specCmds>

Emerson RocPlus

Data Group

The Data group field of the UIS Command Properties dialog box displays the data group affected by a specific component type. The data group must be defined for the remote device before it becomes available for choosing in the Edit Command Component dialog box.

Ord

The Ord field of the UIS Command Properties dialog box displays the ordinal number of the data group affected by a specific component type.

Parameters

Parameters further define a command component. A data group may have zero, one, or more parameters; some are required and some are optional. Actual parameter names depend on the remote device and data group selected. Typical parameters include values, start dates, end dates, and counts. When parameters are required for a certain command component, they populate the Parameters field of the Edit Command Component dialog box. Parameter values may be manually entered there.

If you schedule a command for use in the MSS or issue one from the DDS using the Execute button, required parameters must be defined in the DDS in the Edit Command Component dialog box of the command. You can leave required parameters blank in the DDS if you plan to define them in a UIS Command Button on a CygNet Studio screen or in script. Although multiple parameters can be defined in a UIS Command Button, CygNet Studio can only prompt a user for one parameter.

For information about EIE-specific UIS command component parameters, see topics called UIS Command Component Parameters within their respective Remote Devices subsections.